PREFACE 


About This Book 


This book. Inside Macintosh: AOCE Application Interfaces, describes the 
application programming interfaces (APIs) to Power Talk system software and 
to services provided by PowerShare collaboration servers. The technology 
underlying the PowerTalk and PowerShare software is called the Apple Open 
Collaboration Environment (AOCE). In this book, the term AOCE software 
refers to the Macintosh Operating System managers. Finder extensions, and 
other system software that the PowerTalk desktop interface and PowerShare 
servers use to implement their many features. You can use the AOCE software 
to enhance your application's capabilities. The term PowerTalk system software 
refers specifically to the implementation of the AOCE technology for the 
Macintosh computer, and the term PowerShare collaboration servers refers to 
AOCE-based servers provided by Apple Computer, Inc. The PowerShare 
collaboration servers provide mail, messaging, catalog, security, and time 
services. 

This book shows in detail how your application can take advantage of the 
system software enhancements offered by the AOCE software. It provides a 
complete technical reference to AOCE data structures, AOCE utility routines, 
the Standard Mail Package, the Standard Catalog Package, AOCE templates, 
the Digital Signature Manager, the Interprogram Messaging Manager, the 
Catalog Manager, and the Authentication Manager. 

You need this book if you want to incorporate AOCE features into your 
application or to write AOCE templates to extend the Finder's capability to 
display information in an AOCE catalog. If you are interested in extending the 
capabilities of the AOCE system software to take advantage of services 
offered by external databases and messaging systems, see Inside Macintosh: 
AOCE Service Access Modules. 


What to Read 


The PowerTalk system software and PowerShare servers add many new 
capabilities to the Macintosh Operating System with which you might not yet 
be familiar. For this reason, you should read the first chapter, "Introduction to 
the Apple Open Collaboration Environment," before attempting to use any of 
the software described in this book. That chapter describes some of the uses of 
PowerTalk and PowerShare system software and introduces all of the AOCE 
managers. It discusses some concepts fundamental to an understanding of the 
AOCE software and defines many terms used throughout this book. 

The AOCE software uses several complex, packed data structures whose 
exact contents are private. You must often work with unpacked forms of these 
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structures, compare packed data structures whose contents you cannot read, 
and convert between packed and unpacked forms of structures. For this 
reason, the AOCE software provides a variety of utility routines that you can 
use to pack, unpack, compare, and otherwise manipulate these data 
structures. The chapter "AOCE Utilities" describes these data structures and 
utility routines. You should read this chapter before reading any of the other 
chapters in this book. 

The AOCE software provides several high-level programming interfaces that 
you can use to add PowerTalk and PowerShare capabilities to both existing 
and new applications. 

The chapter "Standard Mail Package" tells you how to add PowerTalk mail 
capabilities to any application. 

The chapter "Standard Catalog Package" tells you how to add 
catalog-browsing and searching services to any application. 

If you want to extend the ability of the Finder to display information in AOCE 
catalogs, you can write a set of resource files called AOCE templates that 
describe the data to be displayed and the format in which it is shown. AOCE 
templates can include code resources that respond to user actions and 
manipulate data. The chapter "AOCE Templates" describes the template 
resources in detail and shows sample templates to help you get started 
writing your own. 

A user can use the PowerTalk system software to add a digital signature to 
any file in the Finder or to sign any letter that has a PowerTalk mailer 
attached. In addition, if you want to allow a user to add a digital signature to 
your application's documents or to any portion of a document, you can use 
the information in the chapter "Digital Signature Manager" to add this 
capability to your application. 

In addition to these high-level programming interfaces, the AOCE software 
provides three low-level managers that you can use to implement messaging, 
catalog, and authentication features in your application. These interfaces are 
intended for use by experienced Macintosh programmers who have a good 
knowledge of Macintosh system software. Whereas the chapters that describe 
the high-level APIs all include sample code and programming hints, the 
chapters on the low-level managers provide less of this sort of information. As 
with all the chapters, they do provide a complete reference to all of the data 
structures and functions provided by these managers. 

You can use the AOCE Interprogram Messaging Manager, described in the 
chapter "Interprogram Messaging Manager," to send messages between 
processes or applications without user intervention. This chapter also may be 
of interest to anyone using the Standard Mail Package or writing a messaging 
service access module (MSAM). An MS AM is an interface between an 
external mail or messaging system and the PowerTalk system software. 

The chapter "Catalog Manager" describes functions you can use to get 
information about AOCE catalogs and to manipulate the data in catalogs. You 
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can use this information to provide catalog-related functions beyond those 
provided by the Standard Catalog Package. This chapter is required reading 
for anyone writing a catalog service access module (CSAM). A CSAM is an 
interface between an external catalog or database and the Power Talk system 
software. 

The chapter "Authentication Manager" describes the functions provided by 
the AOCE authentication service. Some of these functions require you to use 
PowerShare collaboration servers. Other functions described in this chapter 
allow you to implement your own authentication system. 

There is one appendix, "Power Talk Built-in Templates," which describes some 
of the details of the AOCE templates that are built into the Power Talk system 
software. You can use this information to gain access to the information in 
these templates or to provide additional templates that work with and extend 
the built-in templates. 

For your convenience, this book and Inside Macintosh: AOCE Service Access 
Modules include the same glossary of AOCE terminology. Thus, some glossary 
entries refer to topics that are not introduced in this book. 


Format of a Typical Chapter 


Almost all chapters in this book follow a standard structure. For example, the 
chapter "Standard Mail Package" contains these sections: 

■ "About the Standard Mail Package." This section provides an overview of 
the features provided by the Standard Mail Package. 

■ "Using the Standard Mail Package." This section describes the tasks you 
can accomplish using the Standard Mail Package. It describes how to use 
the most common routines, gives related user interface information, 
provides code samples, and supplies additional information. 

■ "Standard Mail Package Reference." This section provides a complete 
reference to the Standard Mail Package by describing the data structures 
and functions that it uses. Each function description also follows a 
standard format, which gives the function declaration and a description of 
every parameter of the function. Some function descriptions also give 
additional descriptive information, such as special considerations and 
cross-references to other sections, chapters, and books. 

■ "Summary of Standard Mail Package." This section provides the Standard 
Mail Package's C interface, as well as the Pascal interface, for the constants, 
data structures, functions, and result codes associated with the Standard 
Mail Package. It also includes some assembly-language interface 
information. 

Some chapters include additional main sections that introduce new concepts 
or discuss certain concepts in detail. For example, in the chapter "Digital 
Signature Manager," the section "About Public-Key Certificates" describes the 
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public-key certificates used by the Digital Signature Manager to verify the 
identity of a signer. In the chapter "Interprogram Messaging Manager," the 
section "Addressing IPM Messages" describes the address format used by the 
Interprogram Messaging Manager. 


Conventions Used in This Book 


Inside Macintosh uses various conventions to present information. Words that 
require special treatment appear in specific fonts or font styles. Certain 
information, such as parameter blocks, use special formats so that you can 
scan them quickly. 


Special Fonts 

All code listings, reserved words, and the names of actual data structures, 
constants, fields, parameters, and functions are shown in Courier (this is 
Courier). 

Words that appear in boldface are key terms or concepts defined in the 
glossary. 


Types of Notes 

Four types of notes are used in this book: 

Note 

A note like this contains general information that is supplemental to the 
main text. (An example appears on page 2-6.) ♦ 

Special topic note 

A note like this contains information about a specific topic that is 
supplemental to the main text. (An example appears on page 5-29.) ♦ 

IMPORTANT 

A note like this contains information that is essential for an 
understanding of the main text and that might cause you problems if 
ignored. (An example appears on page 3-64.) A 

▲ WARNING 

A warning like this indicates a potential problem that you should be 
aware of as you design your software. Failure to head such a warning 
could result in a system crash or loss of data. (An example appears on 
page 5-197.) A 
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Parameter Block Information 

Inside Macintosh presents information about the fields of a parameter block in 
this format: 

Parameter block 

inAndOut Boolean Input /output parameter. 

<r- outputl OSErr Output parameter. 

— » input 1 long Input parameter. 

The arrow in the column at the far left indicates whether the field is an input 
parameter, output parameter, or both. You must supply values for all 
input parameters and input/ output parameters. The function returns values 
in output parameters and input/ output parameters. 

The second column shows the field name as defined in the MPW C interface 
files; the third column indicates the C data type of that field. The fourth 
column provides a brief description of the use of the field. For a complete 
description of each field, see the discussion that follows the parameter block 
or the description of the parameter block in the reference section of the 
chapter. 


Development Environment 


The system software routines described in this book are available using C or 
Pascal interfaces. You can call most of these routines in assembly language, 
but no assembly-language interface files are provided. How you access these 
routines depends on the development environment you are using. This book 
shows system software functions in their C interface using the Macintosh 
Programmer's Workshop (MPW). 

All code listings in this book are shown in C, or, for resources, in Rez in put 
format. They show methods of using various routines and illustrate 
techniques for accomplishing particular tasks. Not all code listings have been 
compiled or tested. These code listings are for illustrative purposes only; 
Apple Computer, Inc., does not intend for you to use these code samples in 
your application. 

This book occasionally uses SurfWriter and SurfDB as the names of 
applications for illustrative purposes; these are not actual products of Apple 
Computer, Inc. In addition, the name River Change Systems is used to represent 
a fictitious company. 
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For More Information 


APDA is Apple's worldwide source for hundreds of development tools, 
technical resources, training products, and information for anyone interested 
in developing applications on Apple platforms. Customers receive the APDA 
Tools Catalog featuring all current versions of Apple development tools and 
the most popular third-party development tools. APDA offers convenient 
payment and shipping options, including site licensing. 

To order products or to request a complimentary copy of the APDA Tools 
Catalog, contact 


APDA 

Apple Computer, Inc. 

PO. Box 319 
Buffalo, NY 14207-0319 

Telephone 1-800-282-2732 (United States) 

1-800-637-0029 (Canada) 
716-871-6555 (International) 


Fax 

AppleLink 
America Online 
CompuServe 
Internet 


716-871-6511 

APDA 

APDAorder 

76666,2405 

APDA@applelink.apple.com 


If you provide commercial products and services, call 408-974-4897 for 
information on the developer support programs available from Apple. 

For information on registering application signatures, file types, Apple events, 
and other technical information, contact 

Macintosh Developer Technical Support 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 303-2T 
Cupertino, CA 95014-6299 
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